Skip to content

feat(core): createReorderable makes List rows reorderable - #8139

Merged
cixzhang merged 24 commits into
meta:mainfrom
vjeux:uikit/c13-list-reorder
Nov 8, 2026
Merged

cixzhang merged 24 commits into
meta:mainfrom
vjeux:uikit/c13-list-reorder

Conversation

@vjeux

@vjeux vjeux commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Stack: #8139 → #8143 → #8163

#8106 has merged, so this sits on main and its own commits are the whole diff. It holds twenty commits: List's reorder (cad762b); reorder mode's hint, with its move buttons and Done (d0c1590), which was #8337, folded in as the stack review asked; a move that renames a row keeps reorder mode (6ff3d0b); the CLI lists a create… factory beside its own hook (66fc409); comment sentences split at 25 words (32d137f); a held finger selects no text (13c6534); a drag reads no layout (ca8a76b); the touch hit area's import from its new place (8de33bf); the stack review's fixes with their two records commits (e5f5e02, 77fb567, 1baf07c, 28b44c3, 0abe4b2, 4b907b5, c89aa9c); and the comment-provenance baseline without the two citations List's comments no longer carry (6beee21). Main is merged in (05c5150). On top come a drop's and a key move's single read before their writes (9a497c6) and the List record's gap line for the shared animator's first-glide read (3384ec6). Main is merged in again (7a333bd), and the reorder measurements drop a batch label the repository never defines (4678530). Main is merged in twice more (ed28397, ff96b6f), and the reorder's handle and session warn once through Core's createDevWarnings, as Dialog, Resizable and TabList do (92365e4).

Why

People reorder playlists, to-do lists and settings on their phones. List can't do it, so apps build their own, often without a keyboard or screen-reader path.

What led to it

This is part of the UIKit-parity program, which makes Astryx's components behave like their iOS counterparts on touch screens. spec:AST-103 defines a reorderable List: createReorderable({onReorder}) makes the behavior, List takes it as reorderable, and each ListItem with an itemKey gets a handle.

  • A finger, on any device, holds a handle 150 ms to pick a row up, and so does a pen where the primary pointer is coarse. A mouse, or a pen where the primary pointer is fine, drags it directly.
  • Activating the handle starts reorder mode. The insertion line marks the row's place, the arrow keys move the row and announce its place, and Escape ends the mode. A move that renames the row, as a list named by place does, keeps the mode.
  • In reorder mode a hint below the handle shows Move up, Move down and Done, so taps or clicks alone can reorder (WCAG 2.2 SC 2.5.7). Each does what its key does, with the same announcement, and focus stays on the handle.
  • Each move calls onReorder({key, to}) once.
<List reorderable={reorderable}>
  {items.map(i => <ListItem key={i.id} itemKey={i.id} label={i.name} />)}
</List>

This builds spec:AST-103 FR1 (but positions() and labels) and FR2 to FR8. AST-103 gains "Implementation gap: not built" notes for FR1's positions() and FR4b's attach, beside its labels note. component:List's readiness line says reorderable is stable and built, but for its labels and positions. family:overlay-dismissal lists the hint among its members. The UIKit table's measured reorder values and the drop model come in here with their first user. With an animatedLayout handle, a drag's commits stay the reorder's own. The CLI lists createReorderable with the hooks.

Options and tradeoffs

  • During the drag: slide rows aside, as UIKit does, or keep them still with a line marking the drop.
  • On touch: pick the row up at once, or after a hold, so a flick still scrolls.
  • In the markup: a wrapper around each row, or only the handle.
  • Moves without a drag: a "Move before / Move after" menu, or a hint that shows them by the row.

Why this choice

design:ordered-collection-reordering chose still rows and a line, because they need no layout work during the drag and look the same everywhere. The hold is UIKit's measured 150 ms. Only the handle is added (spec:AST-103 FR5), so rows keep their layout. DEC-5 chose the hint, because it shows the moves where the row is, without opening a menu. It is the keyboard hint's own layer, and each button's tap area grows toward 44 px on touch through the shared touch hit area. The API is spec:AST-103 FR1's: one behavior object, with no hook twin.

Rebuilt on current main

This head is the change rebuilt on current main, which now has #8106. Five commits follow it:

  • The CLI's hook list: a create… factory documented as a hook lists with the hooks unless its doc names its own use… hook in relatedHooks. Then it is listed beside that hook. So astryx hook --list adds only createReorderable; createAnimator, createPanGesture and createDragToSnapPoints stay beside their hooks, as their docs say.
  • Comments: six comment sentences over 25 words are split, with the same meaning.
  • No text selection under a held handle (vjeux@4613c6f): on iOS a finger held on a reorder handle started a text selection on the row's label, and the drag grew it across the rows. The hold attaches with manageStyle: false, so its handles keep their own touch-action, and the gesture host then leaves the hold's selection lock to the list, which brought none. The list now locks selection on itself from a finger's or a pen's touch-down on a handle until it lifts, through utils/selectionLock; a mouse never takes the lock. A unit test and a Chromium touch case fail without it.
  • No layout read during a drag: the insertion line only writes. The dragged row's span is read once at the pick-up, beside the drag's other measurements, and reorder mode reads before it writes (architecture:react-component-runtime INV18: a per-frame path reads no layout, never interleaved with writes). A new Chromium case traces the crossings of a three-row touch drag: on the previous head each crossing forced a style pass, 4 in all; on this head none.
  • The touch hit area's new place (8de33bf): main's fix(Button): under a finger, a Button's target grows toward 44 px through the shared touch band #10216 moved touchHitArea.stylex from utils/ to internal/, so the reorder handle and its engine import it from there.

The stack review's fixes

  • Edge autoscroll is in the record (28b44c3). Spec owners' ruling, Nov 7 2026: a consistency change under spec:AST-103 FR3. FR3 gains their bullet verbatim, "a held drag near the scroll container's edge scrolls it toward that edge, faster the nearer it is, and stops at the end", and a verification row with its failure expectation. The engine keeps UIKit's measured autoscroll. It starts with the dragged row's edge 8 px inside the scroll edge, at 2 px per 20 ms tick (100 px/s), and rises to 10 px per tick (500 px/s) with that edge 22 px past it. The steps were measured on a UITableView on the iOS 26.2 simulator; the start inset is a guess inside the measured bracket of 3 to 12 pt.
  • One scroller walk (e5f5e02). The engine had its own copy of core's scroll-ancestor walk. nearestScroller, which wraps that walk and falls back to the document's scroller, moves from the keyboard module to utils/scrollingAncestor.ts, and the reorder takes its scroller from there. The keyboard module re-exports it, so its importers keep their imports. The reorder's modules gain no keyboard module, a List without reorderable bundles to the same bytes, and the keyboard target's bundle does not grow.
  • The inline start in right-to-left (77fb567). The preview and the insertion line took the row's physical left as their inline start. So in right-to-left, a row set in from the list's start drew both shifted by its inset. There, they now count the start from the list's right edge.
  • The preview joins no form or radio group (0abe4b2). The preview was a plain clone of the row, so it kept each control's name. Laid beside the row, a copied checked radio took its group from the row's own: the row's radio showed unchecked for the whole drag, and a drop in place left none checked. Core's clone that takes no part in the page (names, ids and labels stripped, no form, inert and hidden) moves from motion/transientCopy.ts into its own module, motion/inertClone.ts, with paintedBackground. The swap's and the layer exit's copies keep building on it, and the transient-copy mechanism stays theirs (architecture:react-component-runtime INV12's boundary test, which gains a case naming the clone's users). The preview is now that clone, with its background from paintedBackground; both read before the pick-up's first write. A row holding a canvas that reads back empty drags as its bare box.
  • A scroll during a drag (4b907b5, c89aa9c). A wheel or trackpad scroll during a mouse drag moved the rows under a still pointer: the preview and the line rode with them, and the drop landed where the pointer had been. The engine now folds a scroll it did not cause into the drag. It reads its scroller's offset once, before its writes: at the next move, autoscroll tick or drop, or else in a later frame once its writes have rendered. Spec owners' ruling, Nov 7 2026: a consistency change, and architecture:react-component-runtime INV18 gains their clause with a verification row: "during a reorder drag, the engine reads its scroller's scroll offset once per frame after a scroll it didn't cause, before its writes". A known limit: while autoscroll runs, a wheel delta that coalesces with the engine's own scroll in one frame is undone by the next tick's write.
  • One layout at the pick-up (1baf07c). The pick-up read the list's position and the row's box after its first writes, and the preview's first offset made its animator read its style back. Every read now comes first, the preview's first offset (none) is not written, and the preview holds its own will-change (architecture:react-component-runtime INV18).
  • One measurement pass at a drop and at a key move (9a497c6, 3384ec6). A drop read each row's layout after writing the row before it, and each write made the row's animator read its style back: 30 forced style passes in Reorder Long List. A reorder mode move read each row between glides too, then scrolled and placed its line after the glides began. Now both read every row, the line's place and the scroll first, then write, and a row left at rest at 0 takes no write. Because the scroll now runs before the rows slide, a key move brings the row's new place into view, not its old one: a row moved down past the screen's bottom edge used to end out of view. One cost remains, which the List record names as a gap: where the primary pointer is coarse, a move forces one more style pass for each row that glides for the first time, because the shared animator reads the row's will-change then.

How to check it

In Storybook Core/List, on a phone or with touch emulation:

  1. Reorderable: hold a grip, drag it two rows down and let go. The row lands there and the others glide.
  2. Flick a grip: the list scrolls.
  3. Tab to a grip, press Enter, press Down twice, then Escape. A screen reader reads each position.
  4. Click a grip: the hint appears with ↑, ↓ and Done. Click ↓ twice, then Done. The row moves two places, and the moves stay.
  5. Reorder From Your UI: choose Move in a row's menu. Reorder mode starts on that row.
  6. Reorder With Pinned Rows: nothing drops above Favorites, but rows move past All mail.
  7. On a desktop, drag a grip with a mouse or a pen: it moves at once, with no hold.
  8. Reorder Long List: drag a grip to the bottom of the screen and hold it there. The list scrolls, faster nearer the edge, and stops once its end is in view.

Gates at the stack's top, which carries this pull request's own commits. The full run is at 4fd0951 (#8163, on main 1c8292c), whose tree differs from c7702fb only in the comment-provenance baseline and one file's formatting; at c7702fb lint, the baseline check, typecheck and the List and Item units ran again:

  • Build, typecheck, ESLint (0 errors), INV29 0, check:knowledge, check:repo, check:i18n-catalog, check:i18n-runtime, check:use-client, check:package-boundaries and the changeset check.
  • Units, after pnpm install --frozen-lockfile: List, createReorderable, motion, Layer, Core's utils and internal entries, the keyboard module, Button, the CLI's hook discovery, every Lab test and the touch-support bundle check, 5,510 of 5,510. The full UI project passes, 22,672 tests. The full node project passes 17,448 tests; its one failure, a CLI block-picker case (build tree › "login form with single sign-on buttons"), fails the same way on main (1c8292c).
  • At 05c5150, a merge of main 7bc8230 with no conflict that leaves this pull request's own changes as they were, the CLI search goldens' isolation test passes again.
  • At this head, 92365e4, which merges main c7558e8: typecheck, ESLint, check:knowledge, check:repo, the CLI search goldens, and Core's List, motion and reorder units (1,209). The two warning tests render twice and fail if either warning repeats. List's interaction specs pass in Chromium (94, 1 skipped), and its reorder specs in WebKit with CI's settings, four CPUs (23, 15 skipped). Merged up through feat(lab): TransferList reorders through core's createReorderable #8143 and feat(lab): ListInput reorders through core's createReorderable #8163, the Lab and List units (275), the TransferList and ListInput reorder specs (13), the full UI project (23,006 tests) and the node project (17,629 tests, no failures) pass. Main's fix(Layout): a full-bleed Table or List row takes the rounded container corner it reaches #10586 had put List.doc.mjs in Prettier's format beside this pull request's anatomy entries; the merge keeps main's file and adds those entries in its format.
  • Red-first (from the stamped head, with the same patch): a move that renamed its row ended reorder mode and was announced with the old names. The new case fails without the fix and passes with it.
  • The stack review's fixes, red-first or against a positive control:
    • The pick-up, traced under a finger from the touch to the first frame: 6 forced style or layout passes on the previous head, none on this one. The crossings stay at none.
    • A wheel scroll of three rows mid-drag: on the previous head the preview and the line rode 111 px from the pointer, and the drop landed where the pointer had been. On this head both are back under the pointer within two rendered frames of the last scroll, and the drop lands three rows further. A layout trace of the wheel, with the pointer moving, finds no forced pass and at most one offset read per scrolled frame; a build that reads inside the scroll event forces a style pass there.
    • A drop and a key move, traced in Chromium. The traces count measurement passes, as architecture:react-component-runtime INV18 states the rule ("one batched measurement pass per change"): when Chromium runs a second style-and-layout round for the same read, as it does while the anchored hint is shown, with the same stack and no write from another stack in between, that round is part of the same pass. A mouse drop in Reorder Long List forced 30 passes on the previous head (05c5150) and at most one on this one. A key move where the primary pointer is coarse forced 4 and now 1, besides at most one more for each row that glides for the first time, which the shared animator adds. A move back over rows that already glided counts every read, the shared animator's included: 4 passes on the previous head, 1 on this one. A finger's drop forced 7 and now 1. A key move of a row at the screen's bottom edge left its new place out of view on the previous head, and brings it into view on this one. Each trace also checks that it saw the input and the rendering after it, so an empty trace cannot pass.
    • A checked radio in the dragged row: it showed unchecked during the drag on the previous head, and stays checked through a drop in place on this one.
    • Right-to-left, with each row set in 32 px from the list's start: the preview and the line sat 32 px off the row on the previous head. On this head they match it in both directions.
    • Autoscroll: a row held at the page's bottom scrolls the page, and stops once the list's end is in view, with the preview still under the pointer. In a 400 px box the list scrolls in, the box scrolls and the page stays. These pass on the previous head and on this one. A build that takes the document as the scroller fails the box case, and one that scrolls past the end fails the stop case.
  • Browser: List's interaction specs in Chromium, 90 passed and 1 skipped. They include the selection lock, both forced-style probes, the radio case, the line in a list set in from its container (LTR and RTL, red by 56 and 16 px before the line-span change), and the two wheel cases. WebKit, with CI's settings (four CPUs): the reorder specs pass 22, and skip 12 Chromium-only cases.

Bundle cost

Measured with the PR size report's build options on the built package (the eager chunks, minified, gzip): List and ListItem import 70.0 KB. With createReorderable they import 114.8 KB, so the reorder adds 44.8 KB where it is used. A List without reorderable imports no reorder, gesture or animator module, only the small module that names the object's key. The stack review's fixes add about 0.9 KB gzip to the reorder's modules, and nothing to a List without reorderable: the same minified bytes (measured on the source with the same options).

Writing rubric results

Over component:List (the readiness line, verified_by, and PR2's implementation-gap sentence for a key move's first glides), spec:AST-103 (two gap notes, and FR3's edge-autoscroll bullet with its verification row), family:overlay-dismissal (the hint joins the members) and architecture:react-component-runtime (INV18's reorder scroll read with its verification row):

R1 narration: none; each edit states what the system does and does not do now.
R2 research: none.
R3 evidence: none; the verification rows and verified_by name tests, not changes.
R4 rejected alternatives: none added.
R5 change references: none; no pull request or issue number in any edit.
R6 open questions: none touched.

Pull request size

This is a behavior-module pull request: 9,235 authored lines in 57 files, without the generated API report: 4,678 of source, 4,125 of tests, and the rest stories, strings, docs and records. The reorder engine, its touch layer, its model, its handle and its hint work only together, so they land as one module.

Evidence

On the iOS simulator, a held drag on a handle before and after the selection lock: the long list before and after, and the ListInput stress story before and after. Before, the loupe and a blue selection show in 2 of 3 takes of the long list and 1 of 2 of ListInput; after, none in 3 and 2 takes.

On iOS 26.2 Safari: a held drag, the drop with the main thread blocked, and tap, Move down, Done. The last was captured before Done took the hint's text role, so Done there is darker and bolder than it is now.

@vercel

vercel Bot commented Oct 24, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 8, 2026 8:46pm UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Oct 24, 2026
@astracat-bot

astracat-bot Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🟢 Reviewed (for maintainers only) Nov 8, 2026, 8:58 PM UTC

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approval is waiting on an engineering-owner decision. No current spec governs List.onReorder, ListItem.isReorderDisabled or the UIKit reorder model (rows slide aside, springs kept under Reduce Motion, no insertion line), so an owner needs to settle that contract and which record governs it: an amended List contract, or spec:AST-094 with its draft requirements approved. Once the governing record states it, any engineering owner, the author included, can record the decision by commenting /approve-spec <full head SHA>. These still need changes whatever that decision is:

  • The diff against main is about 31,000 authored lines from the predecessor stack. Land those pull requests or update the branch so this one carries only the reorder change.
  • Keyboard focus on a reorder handle draws two focus rings, the handle's and the whole row's, and the handle's ring is clipped at the list's edge.
  • The stacked touch row minimum heights change default List row geometry, which the List contract's FR2 says padded preserves.

[Automated review]

@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

PR Analysis Report

🔎 Preview · 92365e4

Storybook · Sandbox · built from this PR's head

Modified components

Component Size LoC Visual · A11y · RTL
charts/ChartTooltip 177.1 kB (+790 B) · 423 B CSS (0) — — · — · —
charts/Chart 199.8 kB (+785 B) · 494 B CSS (0) — — · — · —
lab/Comments 341.6 kB (+771 B) · 2.5 kB CSS (0) — — · — · —
59 more components
Component Size LoC Visual · A11y · RTL
lab/CommentThread 334.6 kB (+762 B) · 2.4 kB CSS (0) — — · — · —
TableCell 109.0 kB (+571 B) · 17.8 kB CSS (0) — — · — · —
lab/TransferList 107.9 kB (+561 B) · 1.7 kB CSS (0) — — · — · —
Markdown 181.1 kB (+556 B) · 20.5 kB CSS (0) — — · — · —
TableHeaderCell 108.5 kB (+542 B) · 17.6 kB CSS (0) — — · — · —
ContextMenu 107.7 kB (+540 B) · 17.4 kB CSS (0) — — · — · —
lab/TransferListSelector 114.4 kB (+535 B) · 1.9 kB CSS (0) — — · — · —
Table 117.9 kB (+510 B) · 18.2 kB CSS (0) — — · — · —
richtext/RichTextEditorToolbar 277.3 kB (+439 B) · 454 B CSS (0) — — · — · —
PowerSearch 284.0 kB (+358 B) · 24.2 kB CSS (0) — — · — · —
ListItem 69.7 kB (+357 B) · 11.4 kB CSS (0) — ✓ · ✓ · ✓
CheckboxListItem 70.8 kB (+346 B) · 11.4 kB CSS (0) — — · — · —
lab/CommentComposer 148.5 kB (+267 B) · 1.9 kB CSS (0) — — · — · —
lab/TabBar 74.9 kB (+240 B) · 1.8 kB CSS (0) — — · — · —
lab/PageControl 73.3 kB (+236 B) · 709 B CSS (0) — — · — · —
lab/NavigationScreen 80.3 kB (+234 B) · 1.5 kB CSS (0) — — · — · —
lab/NavigationStack 80.3 kB (+233 B) · 1.5 kB CSS (0) — — · — · —
CheckboxList 69.0 kB (+184 B) · 8.2 kB CSS (0) — — · — · —
List 18.0 kB (+167 B) · 790 B CSS (0) — ✓ · ✓ · —
BreadcrumbItem 84.1 kB (+134 B) · 12.1 kB CSS (0) — — · — · —
DropdownMenuRadioItem 22.8 kB (+133 B) · 6.6 kB CSS (0) — — · — · —
RadioListItem 67.0 kB (+132 B) · 10.1 kB CSS (0) — — · — · —
Selector 99.1 kB (+130 B) · 17.4 kB CSS (0) — — · — · —
Item · Storybook 17.5 kB (+125 B) · 5.5 kB CSS (0) 1,748 (+38) ✓ · ✓ · —
DropdownMenuCheckboxItem 22.8 kB (+115 B) · 6.6 kB CSS (0) — — · — · —
MoreMenu 96.8 kB (+114 B) · 17.6 kB CSS (0) — — · — · —
DropdownMenuItem 22.0 kB (+109 B) · 6.3 kB CSS (0) — — · — · —
SelectorOption 20.9 kB (+104 B) · 6.1 kB CSS (0) — — · — · —
DropdownMenu 96.5 kB (+103 B) · 17.6 kB CSS (0) — — · — · —
Pagination 109.2 kB (+101 B) · 17.8 kB CSS (0) — — · — · —
ContextMenuItem 29.0 kB (+100 B) · 6.3 kB CSS (0) — — · — · —
SegmentedControl 93.6 kB (+95 B) · 6.9 kB CSS (0) — — · — · —
DropdownMenuSubMenu 69.7 kB (+90 B) · 9.7 kB CSS (0) — — · — · —
TabList 43.4 kB (+87 B) · 6.5 kB CSS (0) — — · — · —
TableSelectionToolbar 70.0 kB (+73 B) · 13.2 kB CSS (0) — — · — · —
Toolbar 43.3 kB (+72 B) · 8.1 kB CSS (0) — — · — · —
DateTimeInput 205.5 kB (+57 B) · 18.7 kB CSS (0) — — · — · —
lab/TourStep 94.9 kB (+33 B) · 590 B CSS (0) — — · — · —
Popover 88.6 kB (+26 B) · 14.2 kB CSS (0) — — · — · —
AppShell 90.4 kB (+21 B) · 13.5 kB CSS (0) — — · — · —
lab/ChatEmojiPicker 103.1 kB (+18 B) · 773 B CSS (0) — — · — · —
TimeInput 159.3 kB (+10 B) · 16.0 kB CSS (0) — — · — · —
lab/ChatReactionBar 104.3 kB (+6 B) · 1.1 kB CSS (0) — — · — · —
SideNav 111.7 kB (+2 B) · 11.4 kB CSS (0) — — · — · —
MultiSelector 94.2 kB (+1 B) · 16.8 kB CSS (0) — — · — · —
TreeList 44.2 kB (+1 B) · 5.6 kB CSS (0) — — · — · —
ChatComposer 77.4 kB (0) · 12.0 kB CSS (0) — — · — · —
ChatComposerInput 75.1 kB (0) · 11.3 kB CSS (0) — — · — · —
ChatComposerTokenElement 75.1 kB (0) · 11.3 kB CSS (0) — — · — · —
ChatLayout 80.5 kB (0) · 10.5 kB CSS (0) — — · — · —
Collapsible 27.1 kB (0) · 4.5 kB CSS (0) — — · — · —
Lightbox 120.0 kB (0) · 10.6 kB CSS (0) — — · — · —
Outline 24.8 kB (0) · 4.1 kB CSS (0) — — · — · —
Slider 106.8 kB (0) · 8.8 kB CSS (0) — — · — · —
Switch 101.3 kB (0) · 9.9 kB CSS (0) — — · — · —
Tokenizer 90.9 kB (0) · 18.8 kB CSS (0) — — · — · —
lab/TabBarItem 3.8 kB (0) · 1.8 kB CSS (0) — — · — · —
DateInput 183.8 kB (−1 B) · 17.0 kB CSS (0) — — · — · —
BottomSheet 65.8 kB (−15 B) · 7.7 kB CSS (0) — — · — · —

Package size:

  • @astryxdesign/cli 3.52 MB packed (+336 B); no new dependencies
  • @astryxdesign/core 7.12 MB packed (+97.6 kB); no new dependencies

API changes: core +5 · ~0 · −0

Committed API report behind this build: cli 29 rows, core 40 rows, theme-butter 1 row, theme-y2k 1 row; run pnpm api:report.

5 API changes (advisory)
Package Where Signature Usage
+ core . · Components · component List prop reorderable?: Reorderable <List reorderable={…} />
+ core . · Functions · function createReorderable function createReorderable: <TKey extends string | number = string | number, TTo = number>(options: ReorderableOptions<TKey, TTo>) => Reorderable<TKey, TTo> import {createReorderable} from '@astryxdesign/core'; createReorderable(…)
+ core . · Types · interface ReorderMove interface ReorderMove<TKey extends string | number = string | number, TTo = number> import type {ReorderMove} from '@astryxdesign/core'
+ core . · Types · interface Reorderable interface Reorderable<TKey extends string | number = string | number, TTo = number> import type {Reorderable} from '@astryxdesign/core'
+ core . · Types · interface ReorderableOptions interface ReorderableOptions<TKey extends string | number = string | number, TTo = number> import type {ReorderableOptions} from '@astryxdesign/core'

Touched components checked; add ci:run-visual, ci:run-a11y or ci:run-rtl to run the full suites.


Generated by PR Enrichment workflow | View full report

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approval is waiting on an engineering-owner decision: no current spec governs List.onReorder, ListItem.isReorderDisabled or the UIKit reorder model (rows slide aside, springs kept under Reduce Motion, no insertion line), so an owner needs to settle that contract and which record governs it, an amended List contract or spec:AST-094 with its draft requirements approved. Once the governing record states it, any engineering owner, the author included, can record the decision by commenting /approve-spec <full head SHA>. These still need changes whatever that decision is:

  • The diff against main is about 31,000 authored lines from the predecessor stack; land those pull requests or update the branch so this one carries only the reorder change.
  • Keyboard focus on a reorder handle draws two focus rings, the handle's and the whole row's, and the handle's ring is clipped at the list's edge.
  • The stacked touch row minimum heights change default List row geometry, which the List contract's FR2 says padded preserves.
  • spec:AST-094 FR7 cites an AST-090 record that does not exist in the repository.

[Automated review]

vjeux added a commit to vjeux/astryx that referenced this pull request Oct 24, 2026
@vjeux

vjeux commented Oct 24, 2026

Copy link
Copy Markdown
Contributor Author

On the predecessor stack: this pull request is stacked, as its first line says, and only its last commit (d67ffca, 10 files, +1,703 −7) is its own. It rebases onto main as each predecessor lands, and the diff then shrinks to that commit.

@cixzhang

Copy link
Copy Markdown
Contributor

Posted by Cindy's agent on her behalf.

Parts of this PR re-implement behavior that already exists, or is being specified, as a shared part of core. Converging keeps one implementation per behavior:

This is about where the behavior lives, not about the PR's intent.

@vjeux

vjeux commented Oct 24, 2026

Copy link
Copy Markdown
Contributor Author

Agreed: one implementation.

The reorder also now keys its motion on the resolver's touch presentation (useTouchPresentation), the same on every touch screen, instead of a platform check.

vjeux added 6 commits November 7, 2026 16:42
The pick-up read the list's position after the rows' first writes and
read the dragged row's box again to place its preview once the list
was positioned. Then it wrote the preview's first offset, and the
preview's animator read its style back twice. Each read forced a style
or layout pass before the first frame, which
architecture:react-component-runtime INV18 rules out.

The pick-up now makes every read first. The preview's span is measured
from the list's padding edge before the list is positioned, and its
first offset, none, needs no write. The preview holds its own
will-change, so its animator reads no stylesheet at its first move.

A new browser case traces the pick-up under a finger: six forced passes
before, none after.
FR3 now states the reorder's edge autoscroll in the spec owners' words:
a held drag near the scroll container's edge scrolls it toward that
edge, faster the nearer it is, and stops at the end. Its verification
row names the browser checks of a drag held near the page's edge and
near the edge of a box the list scrolls in, the unit checks of the
autoscroll step and its timer, and the failures they catch.
The preview was a plain clone of the row, so it kept each control's
name. Laid beside the row, a copied checked radio took its group from
the row's own: the row's radio showed unchecked for the whole drag, and
a drop in place left no radio checked.

The clone that takes no part in the page moves from transientCopy.ts
into its own module, inertClone.ts, with paintedBackground: names, ids
and labels stripped, no form, inert and hidden. The swap's and the
layer exit's copies keep it through inertCopy, and the transient copy
mechanism stays theirs. The preview is now that clone, and its
background comes from paintedBackground. The clone reads the row's
styles, so it is made before the pick-up's first write. A boundary test
keeps the clone to the copy mechanism and the reorder's preview.

A new browser case drags a row whose radio is checked: the radio showed
unchecked during the drag before, and stays checked now, through a drop
in place.
The drag placed its preview and line from the pick-up's snapshot, plus
its own autoscroll. A wheel or trackpad scroll during a mouse drag
moved the rows under a still pointer: the preview and the line rode
with them, and the drop landed where the pointer had been.

The engine now watches its scroller's scroll events through
subscribeInput, and skips the ones its own autoscroll causes. After any
other, it reads the scroller's offset once, before its writes: at the
next move, the next autoscroll tick or the drop, or else in a later
frame once the writes so far have rendered. So the read forces no
layout. The change in the offset joins the drag's own scrolled
distance, and the preview and the line are placed again.

Two new browser cases wheel three rows mid-drag. On the previous head
the preview and the line rode 111 px from the pointer; now both stay
under it, and the drop lands three rows further. A layout trace of the
wheel with the pointer moving finds no forced pass, and at most one
offset read per scrolled frame. A build that reads in the scroll event
itself forces a style pass there.
INV18 names one more read a scroll path may make, in the spec owners'
words: during a reorder drag, the engine reads its scroller's scroll
offset once per frame after a scroll it didn't cause, before its
writes. A verification row names the browser checks: a wheel scroll
mid-drag keeps the preview and the drop line under the pointer, with
no forced layout and one read per such frame.
The first commit removed two record citations from comments in List.tsx
and ListItem.tsx. The comment-provenance baseline still listed both,
so its check failed. The baseline script, run again, drops only those
two entries.

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested. The List reorder follows current spec:AST-103 and the reorder design, and the record edits are owner-approved for this head. Two findings block it:

  • Found by CI: test-node (1/4) and the test gate fail the WebKit leg guard in .github/scripts/playwright-legs.test.mjs ("98 changed specs: 2073 s of proofs: expected 5 to be less than 5"), because the three new ListReorder*.interaction.browser.spec.ts files have no recorded times; updating the branch from main, which now runs pr-interaction-webkit on six legs, or recording their WebKit times in .github/playwright-leg-durations.json should clear it.
  • Miss: each drop forces one style recalculation per row in the drop's task (6 in the Reorderable story and 30 in Reorder Long List, traced in Chromium), because rebase() in listReorderEngine.tsx (lines 1724-1761) calls animatorFor(row).set({y: 0}) between per-row layoutTop reads and each call reads computed style after its write; reading every row's layout first and skipping the write for rows already at rest keeps the drop to one layout, as architecture:react-component-runtime INV18 requires.

Non-blocking: the preview's 0.6 opacity also dims its background, so the rows under it show through; a scroll of an ancestor of the list's scroller is not followed during a drag; and the reorderPickedUp translator note still says keys pick a row up.

This is the bottom of the stack #8139 → #8143 → #8163, so a fix here also moves the two pull requests above it.

[Automated review]

* UIKit's reorder control (iOS 26.2, measured): a finger held still on it for
* the scroll view's content-touch delay (150 ms) claims the drag. A flick that
* starts on it scrolls the table instead. So the handle lets the browser pan
* vertically and pinch-zoom until the claim, through its own `touch-action`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking (architecture:knowledge-contracts INV29): the handle's touch-action is manipulation (ListReorderHandle.tsx:142), which leaves both pan axes and pinch-zoom, not a vertical pan only. Suggested: "Until the claim, the handle leaves the browser its pans and pinch-zoom (manipulation)."

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, manipulation leaves both pans and pinch-zoom. I'll fix the comment in a follow-up once this stack merges.

return row.offsetLeft - base;
}

function isTransparent(color: string): boolean {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: this is a fourth copy of Core's inline transparent-colour test (motion/inertClone.ts:122, motion/animatedLayout.ts:1835, AppShell/AppShell.tsx:1052), and it already differs from them by accepting / 0). Exporting one predicate beside paintedBackground in motion/inertClone.ts would keep the copies in step.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, one predicate exported beside paintedBackground should replace the four copies. A follow-up does that once this stack merges.

@cixzhang

cixzhang commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

/approve-spec 6beee21

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approval waits on an engineering owner's decision, and one fix is needed. The List reorder follows current spec:AST-103 and the reorder design, and the merge with main changes nothing in it, but a new commit needs the record edits approved again.

  • The three record edits the reorder rests on need an engineering owner's approval for this head: spec:AST-103 FR3's edge-autoscroll bullet, architecture:react-component-runtime INV18's exception for the reorder drag's scroll read, and family:overlay-dismissal's new member, List's reorder-mode hint, each with its verification row; an engineering owner records the decision by commenting /approve-spec <full head SHA>, and the author can do so as one.
  • Miss: each drop forces one style recalculation per row in the drop's own task (6 in the Reorderable story, 30 in Reorder Long List), because rebase() in listReorderEngine.tsx (lines 1721-1764) calls animatorFor(row).set({y: 0}) between per-row layoutTop reads and each call reads computed style after its write; reading every row's layout first and skipping the write for rows already at rest keeps the drop to one layout, as architecture:react-component-runtime INV18 requires.

CI: the WebKit leg-guard failure from the last review is gone with the merge, and the one failing proof, a Layer entrance check that counted one layout in the third of three DropdownMenu submenu opens, passed five reruns against this head's Storybook, so a rerun should clear it. Non-blocking: the preview's 0.6 opacity also dims its background; a scroll of an ancestor of the list's scroller is not followed during a drag; and the reorderPickedUp translator note still says keys pick a row up.

[Automated review]

vjeux added 2 commits November 8, 2026 04:49
A drop read each row's layout after writing the row before it, and
read the theme's motion tempo again for each gliding row. So it forced
one style pass per row: 30 for a 30-row list in Chromium. A reorder
mode key move read each row between glides too, then scrolled to the
row and placed the insertion line after the glides had started.

Both now read every row, the line's place and the scroll first, and
write after. A row left at rest at 0 takes no write, since each
animator write reads its style back. The scroll now runs before the
rows slide, so it brings the row's new place into view, not its old
one. A spring back reads the tempo once too.
Where the primary pointer is coarse, a reorder mode move forces one
style pass for each row that glides for the first time: the shared
animator reads the row's will-change then. The List record names this
as an implementation gap.
@cixzhang

cixzhang commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

/approve-spec 05c5150

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested. The List reorder follows current spec:AST-103 and the reorder design, and an engineering owner has approved this head's record edits, so one fix stands between this pull request and approval.

  • Miss: each drop forces one style recalculation per row in the drop's own task (6 in the Reorderable story, 30 in Reorder Long List), because rebase() in listReorderEngine.tsx (lines 1721-1764) calls animatorFor(row).set({y: 0}) between per-row layoutTop reads and each call reads computed style after its write; reading every row's layout first and skipping the write for rows already at rest keeps the drop to one layout, as architecture:react-component-runtime INV18 requires.

This is the bottom of the #8139 → #8143 → #8163 stack, so the pull requests above it land only after it is approved. CI's one failure, a Layer entrance proof in pr-interaction (5/6), is not one of this pull request's specs and passed repeated runs against this head's Storybook, so a rerun should clear it. Non-blocking: the preview's 0.6 opacity also dims its background, a scroll of an ancestor of the list's scroller is not followed during a drag, and the reorderPickedUp translator note still says keys pick a row up.

[Automated review]

@cixzhang

cixzhang commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

/approve-spec 3384ec6

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved. CI passes on this head.

The drop's per-row style recalculation is fixed: rebase() now reads every row before its first write and skips the write for a row already at rest, and a drop in the 30-row story forces no style or layout pass in the reorder's own code. With an engineering owner's approval of this head's record edits, the reorder follows spec:AST-103 and the reorder design.

Non-blocking, for the follow-ups already planned: the preview's 0.6 opacity also dims its background, a scroll of an ancestor of the list's scroller is not followed during a drag, and the reorderPickedUp translator note still says keys pick a row up.

[Automated review]

vjeux added 2 commits November 8, 2026 06:43
Main's meta#8215 rewrote the zoom section of motion/MEASUREMENTS.md, the
last section before the reorder section this pull request appends.
The resolution keeps main's zoom text and table, then the reorder
section as it was.
The reorder section and the reorder constants' sources named their
measurement batches by a label the repository never defines. They now
give the lab, device and date, as the other measured sources do.
@cixzhang

cixzhang commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

/approve-spec 4678530

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved. CI passes on this head.

Since the last review, the reorder's measurement notes name their lab, device and date instead of a batch label, and the merge with main keeps both sides of the measurements file; nothing that runs changes. With an engineering owner's approval of this head's record edits, the reorder follows spec:AST-103 and the reorder design.

Non-blocking, for the follow-ups already planned: the preview's 0.6 opacity also dims its background, a scroll of an ancestor of the list's scroller is not followed during a drag, and the reorderPickedUp translator note still says keys pick a row up.

[Automated review]

@cixzhang

cixzhang commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

/approve-spec 4678530

2 similar comments
@cixzhang

cixzhang commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

/approve-spec 4678530

@cixzhang

cixzhang commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

/approve-spec 4678530

@cixzhang

cixzhang commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

/approve-spec ed28397

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested. The List reorder follows current spec:AST-103 and the reorder design, and an engineering owner approved this revision's record edits; one shared-path fix remains.

  • Regression: ListReorderHandle.tsx:275 (warnedNamelessRef) and listReorderEngine.tsx:705 (warnedUnkeyed) keep their own warn-once flags, while createDevWarnings in utils/devWarning.ts, which the merge with main brought in, now owns per-instance warning deduplication (Dialog, Resizable and TabList use it), so call it from the handle (useState(createDevWarnings)) and the session (a createDevWarnings() field) and delete both flags.

main has moved since this revision and now conflicts in packages/core/src/List/List.doc.mjs, so resolve that when you push the fix. The non-blocking notes (the preview's opacity over its own background, an ancestor scroll during a drag, the reorderPickedUp translator note, the touch-action comment, the fourth transparent-colour test) still stand for the planned follow-ups.

[Automated review]

vjeux added 2 commits November 8, 2026 11:02
Main's meta#10586 put List.doc.mjs in Prettier's format and changed edge's
bleed text, beside the reorderable prop and anatomy entries this pull
request adds. The resolution keeps main's file and adds this pull
request's entries in that format.
The reorder handle and the reorder session each kept a flag of their
own to warn once. Core's createDevWarnings now owns per-instance
warn-once, as Dialog, Resizable and TabList use it, so both call it
and the flags go. Each still warns once: a handle about a row with no
name, a session about rows with no item key. The two warning tests
now render twice, so a second warning fails them.
@cixzhang

cixzhang commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

/approve-spec 92365e4

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved. CI passes on this head.

The shared-path fix is in: the reorder handle and the reorder session now warn once through Core's createDevWarnings, and both warning tests check that a second render adds no second warning. An engineering owner approved this revision's record edits, and the rest of the reorder follows current spec:AST-103 and the reorder design.

Non-blocking follow-ups, as discussed in the threads:

  • The 0.6-opacity preview lets the rows under it show through; dimming its content with an opaque background would read more clearly.
  • watchScroll follows only its own scroller, so a scroll of an ancestor scroller during a drag is not folded in.
  • The reorderPickedUp translator note still says the handle's keys pick a row up, the ListReorderTouch.ts header comment says the handle allows only vertical panning, and isTransparent is a fourth copy of Core's transparent-colour test.

[Automated review]

This branch was successfully deployed

1 active deployment
Preview — 92365e48 Deployed Nov 8, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci:run A maintainer lets this outside contributor's pull request run CI (AST-030 FR17) CLA Signed This label is managed by the Meta Open Source bot. needs:design-review Affects visuals — Design should review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants